home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / history.n < prev    next >
Text File  |  1994-09-20  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. history(n)            Tcl Built-In Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      history - Manipulate the history list
  12.  
  13. SYNOPSIS
  14.      history ?_o_p_t_i_o_n? ?_a_r_g _a_r_g ...?
  15. _________________________________________________________________
  16.  
  17.  
  18. DESCRIPTION
  19.      The history  command  performs  one  of  several  operations
  20.      related  to recently-executed commands recorded in a history
  21.      list.  Each of these recorded commands is referred to as  an
  22.      ``event''.  When specifying an event to the history command,
  23.      the following forms may be used:
  24.  
  25.      [1]  A number:  if positive, it refers  to  the  event  with
  26.           that  number  (all  events are numbered starting at 1).
  27.           If the number is negative, it selects an event relative
  28.           to  the current event (-1 refers to the previous event,
  29.           -2 to the one before that, and so on).
  30.  
  31.      [2]  A string:  selects the most recent event  that  matches
  32.           the string.  An event is considered to match the string
  33.           either if the string is the same as the  first  charac-
  34.           ters  of  the event, or if the string matches the event
  35.           in the sense of the string match command.
  36.  
  37.      The history command can take any of the following forms:
  38.  
  39.      history
  40.           Same as history info, described below.
  41.  
  42.      history add _c_o_m_m_a_n_d ?exec?
  43.           Adds the _c_o_m_m_a_n_d argument to the history list as a  new
  44.           event.   If exec is specified (or abbreviated) then the
  45.           command is also executed and its  result  is  returned.
  46.           If  exec  isn't  specified  then  an  empty  string  is
  47.           returned as result.
  48.  
  49.      history change _n_e_w_V_a_l_u_e ?_e_v_e_n_t?
  50.           Replaces the value recorded for an event with _n_e_w_V_a_l_u_e.
  51.           _E_v_e_n_t  specifies  the event to replace, and defaults to
  52.           the _c_u_r_r_e_n_t event (not  event  -1).   This  command  is
  53.           intended  for  use in commands that implement new forms
  54.           of history substitution and wish to replace the current
  55.           event (which invokes the substitution) with the command
  56.           created through substitution.  The return value  is  an
  57.           empty string.
  58.  
  59.      history event ?_e_v_e_n_t?
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. history(n)            Tcl Built-In Commands
  71.  
  72.  
  73.  
  74.           Returns the value of the event given by  _e_v_e_n_t.   _E_v_e_n_t
  75.           defaults  to  -1.  This command causes history revision
  76.           to occur: see below for details.
  77.  
  78.      history info ?_c_o_u_n_t?
  79.           Returns a formatted  string  (intended  for  humans  to
  80.           read)  giving the event number and contents for each of
  81.           the events in  the  history  list  except  the  current
  82.           event.  If _c_o_u_n_t is specified then only the most recent
  83.           _c_o_u_n_t events are returned.
  84.  
  85.      history keep _c_o_u_n_t
  86.           This command may be used to change the size of the his-
  87.           tory  list  to  _c_o_u_n_t events.  Initially, 20 events are
  88.           retained in the history list.  This command returns  an
  89.           empty string.
  90.  
  91.      history nextid
  92.           Returns the number of the next event to be recorded  in
  93.           the  history list.  It is useful for things like print-
  94.           ing the event number in command-line prompts.
  95.  
  96.      history redo ?_e_v_e_n_t?
  97.           Re-executes the command indicated by _e_v_e_n_t  and  return
  98.           its  result.   _E_v_e_n_t  defaults  to  -1.   This  command
  99.           results in history revision:  see below for details.
  100.  
  101.      history substitute _o_l_d _n_e_w ?_e_v_e_n_t?
  102.           Retrieves the command given by _e_v_e_n_t (-1  by  default),
  103.           replace  any  occurrences  of _o_l_d by _n_e_w in the command
  104.           (only simple character equality is supported;  no  wild
  105.           cards),  execute  the resulting command, and return the
  106.           result of that execution.  This command results in his-
  107.           tory revision:  see below for details.
  108.  
  109.      history words _s_e_l_e_c_t_o_r ?_e_v_e_n_t?
  110.           Retrieves from  the  command  given  by  _e_v_e_n_t  (-1  by
  111.           default)  the words given by _s_e_l_e_c_t_o_r, and return those
  112.           words in a string separated by  spaces.   The  selector
  113.           argument  has  three  forms.   If it is a single number
  114.           then it selects the word given by that  number  (0  for
  115.           the command name, 1 for its first argument, and so on).
  116.           If it consists of two numbers separated by a dash, then
  117.           it selects all the arguments between those two.  Other-
  118.           wise selector is treated as a pattern; all words match-
  119.           ing  that  pattern  (in  the sense of string match) are
  120.           returned.  In the numeric forms $ may be used to select
  121.           the  last  word of a command.  For example, suppose the
  122.           most recent command in the history list is
  123.  
  124.                format  {%s is %d years old} Alice [expr $ageInMonths/12]
  125.  
  126.           Below are some history commands and  the  results  they
  127.  
  128.  
  129.  
  130. Tcl                                                             2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. history(n)            Tcl Built-In Commands
  137.  
  138.  
  139.  
  140.           would produce:
  141.  
  142.  
  143.                history words $ [expr $ageInMonths/12]
  144.                history words 1-2{%s is %d years  old} Alice
  145.                history words *a*o*{%s is %d years old} [expr $ageInMonths/12]
  146.  
  147.           History words results in history revision:   see  below
  148.           for details.
  149.  
  150. HISTORY REVISION
  151.      The history  options  event,  redo,  substitute,  and  words
  152.      result  in  ``history revision''.  When one of these options
  153.      is invoked then the current event is modified  to  eliminate
  154.      the  history  command  and replace it with the result of the
  155.      history command.  For example, suppose that the most  recent
  156.      command in the history list is
  157.  
  158.           set a [expr $b+2]
  159.      and suppose that the next command invoked is one of the ones
  160.      on  the  left side of the table below.  The command actually
  161.      recorded in the history event will be the corresponding  one
  162.      on the right side of the table.
  163.  
  164.  
  165.           history redo    set a [expr $b+2]
  166.           history s a b   set b [expr $b+2]
  167.           set c [history w 2]set c [expr $b+2]
  168.  
  169.      History revision is needed because event specifiers like  -1
  170.      are  only valid at a particular time:  once more events have
  171.      been added to the history list a different  event  specifier
  172.      would  be needed.  History revision occurs even when history
  173.      is invoked indirectly from the current event  (e.g.  a  user
  174.      types  a  command  that invokes a Tcl procedure that invokes
  175.      history):  the top-level command whose execution  eventually
  176.      resulted  in  a history command is replaced.  If you wish to
  177.      invoke commands like history words without history revision,
  178.      you  can use history event to save the current history event
  179.      and then use history change to restore it later.
  180.  
  181.  
  182. KEYWORDS
  183.      event, history, record, revision
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.